> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jaypopat/cf_ai_duet/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/rooms/{roomID}/message

> Send a message to the AI assistant and receive a response

Sends a user message to the Duet AI assistant for a specific room. The assistant maintains conversation history and can execute sandboxed commands using `<run>` tags.

## Endpoint

```
POST /api/rooms/{roomID}/message
```

## Path Parameters

<ParamField path="roomID" type="string" required>
  Unique identifier for the conversation room. Used to maintain isolated conversation state and sandbox environments.
</ParamField>

## Request Body

<ParamField body="text" type="string" required>
  The user's message text. Must be at least 1 character long.

  ```typescript theme={null}
  text: z.string().min(1, "Text cannot be empty")
  ```
</ParamField>

<ParamField body="userId" type="string">
  Optional identifier for the user sending the message. Used to track message authorship in multi-user scenarios.
</ParamField>

## Response

<ResponseField name="reply" type="string">
  The AI assistant's response text. May include command outputs if the assistant executed sandbox commands.
</ResponseField>

<ResponseField name="messages" type="DuetMessage[]">
  The complete conversation history for this room (last 50 messages). Each message includes:

  <Expandable title="DuetMessage Schema">
    <ResponseField name="role" type="'user' | 'agent'">
      The message sender type
    </ResponseField>

    <ResponseField name="userId" type="string">
      User identifier (only present for user messages)
    </ResponseField>

    <ResponseField name="text" type="string">
      The message content
    </ResponseField>

    <ResponseField name="ts" type="number">
      Unix timestamp in milliseconds
    </ResponseField>
  </Expandable>
</ResponseField>

## AI Behavior

The assistant uses the `@cf/meta/llama-3-8b-instruct` model with the following system prompt:

> "You are Duet, a concise pair-programming assistant. You can run commands in a sandbox using `<run>command</run>` tags. When asked to perform an action, briefly explain what you will do and wrap the exact shell command(s) in `<run>` tags. Do NOT include predicted output in your response - just provide the explanation and command."

The assistant automatically executes commands wrapped in `<run>` tags and appends output to the response.

## Example Request

```bash theme={null}
curl -X POST https://your-worker.workers.dev/api/rooms/room-123/message \
  -H "Content-Type: application/json" \
  -d '{
    "text": "List all files in the current directory",
    "userId": "user-456"
  }'
```

## Example Response

```json theme={null}
{
  "reply": "I'll list the files in the current directory.\n\nOutput (ls -la):\ntotal 12\ndrwxr-xr-x 2 user user 4096 Mar 1 10:30 .\ndrwxr-xr-x 3 user user 4096 Mar 1 10:29 ..\n-rw-r--r-- 1 user user  128 Mar 1 10:30 example.txt",
  "messages": [
    {
      "role": "user",
      "userId": "user-456",
      "text": "List all files in the current directory",
      "ts": 1709287800000
    },
    {
      "role": "agent",
      "text": "I'll list the files in the current directory.\n\nOutput (ls -la):\n...",
      "ts": 1709287801500
    }
  ]
}
```

## Error Responses

### 400 Bad Request

Returned when request validation fails:

```json theme={null}
{
  "error": "invalid request",
  "details": {
    "text": ["Text cannot be empty"]
  }
}
```

### 404 Not Found

Returned when the room ID is missing from the URL path.

### 405 Method Not Allowed

Returned when using a method other than POST.

## Implementation Details

* Conversation history is limited to the last 10 messages when calling the AI model (cf-worker/index.ts:164)
* Total message history stored per room: 50 messages (cf-worker/index.ts:179)
* Command output is truncated to 500 characters (cf-worker/index.ts:200)
* Sandbox instances are isolated per room using naming pattern: `sandbox-{roomID}` (cf-worker/index.ts:196)

## Related Endpoints

* [POST /api/rooms/{roomID}/sandbox/exec](/api/sandbox-exec) - Execute commands directly without AI
* [DELETE /api/rooms/{roomID}](/api/room-cleanup) - Clean up room resources